From e5ae946be36589e7b946f3a87f8e41127caa872e Mon Sep 17 00:00:00 2001
From: Daniel Boles <dboles@src.gnome.org>
Date: Fri, 17 Mar 2017 23:55:15 +0000
Subject: [PATCH] css-overview: Elaborate how color expressions work

---
 docs/reference/gtk/css-overview.xml | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/docs/reference/gtk/css-overview.xml b/docs/reference/gtk/css-overview.xml
index d5e6cf2cf3..3a7925e2b5 100644
--- a/docs/reference/gtk/css-overview.xml
+++ b/docs/reference/gtk/css-overview.xml
@@ -582,9 +582,14 @@ background-color: @bg_color;
     </example>
 
     <para>
-      GTK+ also allows to form color expressions, which can be nested and
-      provide a rich language to define colors which are derived from a
-      set of base colors.
+      GTK+ also supports color expressions, which allow colors to be transformed
+      to new ones and can be nested, providing a rich language to define colors.
+    </para>
+    <para>
+      Color expressions resemble functions, taking 1 or more colors and in some
+      cases a number as their arguments. The number is floating-point, clamped
+      between 0 and 1, and specifies the degree to which the expression will
+      transform the given color(s) in the manner that is indicated by its name.
     </para>
 
 <literallayout><code>〈color expression〉 = lighter(〈color〉) | darker(〈color〉) | shade(〈color〉,〈number〉) | alpha(〈color〉,〈number〉) | mix(〈color〉,〈color〉,〈number〉)</code>
-- 
2.30.2